<?php

namespace maotool\db;

interface Connection
{

    /**
     * 启动事务
     *
     * @return void
     */
    public function startTrans();

    /**
     * 用于非自动提交状态下面的查询提交.
     *
     * @return void
     */
    public function commit();

    /**
     * 事务回滚.
     *
     * @return void
     */
    public function rollback();

    /**
     * 关闭连接（或者重新连接）.
     *
     * @return $this
     */
    public function close();

    /**
     * 执行SQL查询并返回结果集.
     *
     * @param string $sql SQL语句
     * @param array $params 绑定参数
     * @return array
     */
    public function query($sql, array $params = array());

    /**
     * 执行SQL语句（如INSERT, UPDATE, DELETE）并返回受影响的行数.
     *
     * @param string $sql SQL语句
     * @param array $params 绑定参数
     * @return int
     */
    public function execute($sql, array $params = array());

    /**
     * 获取最后插入的ID.
     *
     * @return int|string
     */
    public function getLastInsertId();

    /**
     * 设置连接的超时时间.
     *
     * @param int $timeout 超时时间（秒）
     * @return void
     */
    public function setTimeout($timeout);

    /**
     * 获取当前连接的状态.
     *
     * @return string
     */
    public function getStatus();

    /**
     * 设置连接的字符集.
     *
     * @param string $charset 字符集
     * @return void
     */
    public function setCharset($charset);

    /**
     * 获取数据库类型（如MySQL、PostgreSQL等）.
     *
     * @return string
     */
    public function getType();

    /**
     * 设置当前的缓存对象
     *
     * @param mixed $cache 缓存对象
     * @return void
     */
    public function setCache($cache);

    /**
     * 获取数据库的配置参数.
     *
     * @param string $config 配置名称
     * @return mixed
     */
    public function getConfig($config = '');

    /**
     * 设置数据库的配置参数.
     *
     * @param string $config 配置名称
     * @param mixed $value 配置值
     * @return void
     */
    public function setConfig($config, $value);

    /**
     * 获取连接是否处于事务中.
     *
     * @return bool
     */
    public function inTransaction();

    /**
     * 获取连接是否已关闭.
     *
     * @return bool
     */
    public function isClosed();

    /**
     * 获取连接是否只读.
     *
     * @return bool
     */
    public function isReadOnly();

    /**
     * 设置连接是否只读.
     *
     * @param bool $readOnly 是否只读
     * @return void
     */
    public function setReadOnly($readOnly);

    /**
     * 获取连接的元数据.
     *
     * @return array
     */
    public function getMetaData();

    /**
     * 获取连接的自动提交状态.
     *
     * @return bool
     */
    public function getAutoCommit();

    /**
     * 设置连接的自动提交状态.
     *
     * @param bool $autoCommit 是否自动提交
     * @return void
     */
    public function setAutoCommit($autoCommit);

}